All Databases Inside Mac - AppleEvents

AEInstallEventHandler

Install an event handler

#include <AppleEvents.h> Apple Event Manager

OSErr AEInstallEventHandler ( theAEEventClass, theAEEventID,

handler, handlerRefcon, isSysHandler );

AEEventClass theAEEventClass ; event class to be dispatched

AEEventID theAEEventID ; event ID to be dispatched

EventHandlerProcPtr handler ; pointer to event handler routine

long handlerRefcon ; reference constant

Boolean isSysHandler ; TRUE = added to system coercion table

FALSE = added to application coercion table

returns Error Code; 0 = no error

AEInstallEventHandler installs an Apple event handler in either the

application or the system Apple event dispatch table..

theAEEventClass The event class for the Apple event or events to be dispatched for

this entry.

theAEEventID The event ID for the Apple event or events to be dispatched for this

entry.

handler A pointer to an Apple event handler for this dispatch table entry.

Note that a handler in the system dispatch table must reside in the

system heap; this means that if the value of the isSysHandler

parameter is TRUE, the handler parameter should point to a location

in the system heap. Otherwise, if you put your system handler code

in your application heap, you must remove the handler before your

application terminates by using the AEGetEventHandler function.

See the Notes section below for the syntax for an Apple event handler.

handlerRefCon A reference constant that is passed by the Apple Event Manager

to the handler each time the handler is called. If your handler doesn't

use a reference constant, use 0 as the value of this parameter.

isSysHandler Specifies the Apple event dispatch table to which you want to add the

handler. If the value of isSysHandler is TRUE, the

Apple Event Manager adds the handler to the system Apple event

dispatch table. Entries in the system Apple event dispatch table are

available to all applications. If the value of isSysHandler is FALSE,

the Apple Event Manager adds the handler to your application's

Apple event dispatch table. The application's Apple event dispatch

table is searched first; the system Apple event dispatch table is

searched only if the necessary handler is not found in your

applications Apple event dispatch table.

Result codes

noErr (0) No error

paramErr (-50) parameter error ( handler pointer is NIL or odd)

memFullErr (-108) Not enough room in heap zone

Notes: The parameters theAEEventClass and theAEEventID specify the event class

and event ID of the Apple events to be handled by the handler for this

dispatch table entry. For these parameters, you must provide one of the

following combinations:

• the event class and event ID of a single Apple event to be dispatched to

the handler for this dispatch table entry

• the typeWildCard constant for theAEEventClass and an event ID for

theAEEventID, which indicates that Apple events from all

event classes whose event IDs match theAEEventID should be

dispatched to the handler for this dispatch table entry.

• an event class for theAEEventClass and the typeWildCard constant for

theAEEventID, which indicates that all events from the

event class theAEEventClass should be dispatched to the handler for

this dispatch table entry

• the typeWildCard constant for both the parameters theAEEventClass

and theAEEventID, which specifies that all Apple events should be

dispatched to the handler for this dispatch table entry.

IMPORTANT: If you use the typeWildCard constant for either the

theAEEventClass or the theAEEventID parameter (or for both), the

corresponding handler must return the error errAEEventNotHandled if it

does not handle a particular event.

The handler parameter is a pointer to an Apple event handler for this

dispatch table entry. Note that a handler in the system dispatch table must

reside in the system heap; this means that if the value of the isSysHandler

parameter is TRUE, the handler parameter should point to a location in the

system heap. Otherwise, if you put your system handler code in your

application heap, you must remove the handler when your application quits

by using the AERemoveEventHandler function.

Each handler must be a function that uses this syntax:

OSErr MyEventHandler(AppleEvent * theAppleEvent,

AppleEvent * reply, long handlerRefcon);

The parameter theAppleEvent is the Apple event to handle. Your handler

uses Apple Event Manager functions to extract any parameters and

attributes from the Apple event and then performs the necessary

processing. The reply parameter is the default reply provided by the

Apple Event Manager. The handlerRefcon parameter is the

reference constant stored in the Apple event dispatch table entry for the

Apple event. Your handler can ignore this parameter if your application does

not use the reference constant.

If there was already an entry in the specified event handler table for the

same event class and event ID, it is replaced. Therefore, before installing a

handler for a particular Apple event into the system event dispatch table,

use the AEGetEventHandler function to determine whether the table

already contains a handler for that event. If an entry exists,

AEGetEventHandler returns a reference constant and a pointer to that

event handler. Chain these to your event handler by providing pointers to

the previous handler and its reference constant in the handlerRefcon

parameter of AEInstallEventHandler. When your handler is finished,

use these pointers to call the previous handler. If you remove your system

handler, be sure to reinstall the chained handlers.

When an application calls a system Apple event handler, the A5 register is

set up for the calling application. For this reason, if you provide a system

Apple event handler, it should never use A5 global variables or anything

that depends on a particular context; otherwise, the application that calls

the system handler may crash.

For additional information on Apple event handlers, see

Writing Apple Event Handlers.

For an example of a program which uses the AEInstallEventHandler

routine, see Installing Apple Event Handlers.

Referenced by (17):